home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 May / EnigmA AMIGA RUN 18 (1997)(G.R. Edizioni)(IT)[!][issue 1997-05][EAR-CD II].iso / softwareupdate / system / amigados / handlers / handlers.doc < prev    next >
Text File  |  1996-10-10  |  19KB  |  566 lines
  1. 6    HANDLERS
  2.  
  3. 6.1  INTRODUCTION
  4.  
  5. AmigaDOS can use a lot of different devices or handlers as they
  6. are also called. The most commonly used handler is the "file
  7. handler" which we have worked with in the previous chapters.
  8. The other handlers will be described in this chapter, but as
  9. you will soon notice, these other handlers are controlled in
  10. much the same manner.
  11.  
  12. The other handlers give you access to the printer, parallel and
  13. serial port, console windows, the speech synthesizer, and will
  14. even let you send data between two or more programs.
  15.  
  16.  
  17.  
  18. 6.2  AVAILABLE HANDLERS
  19.  
  20. Here is a list of all available AmigaDOS handlers: (See picture
  21. "Handlers.pic" as an illustration)
  22.  
  23.   1. File handler. Read and write files, unbuffered as well as
  24.      buffered.
  25.        Devices: (4 disk drives) "DF0:", "DF1:", "DF2:", "DF3:"
  26.                 (Hard disks)  "DHx:" (x = 0, 1, 2, 3...)
  27.                 (Other file devices) "RAM:"...  
  28.   
  29.   2. Buffered and translated console handler (input/output in
  30.      a "Console window"). Translation means that you can
  31.      included special commands in the data which will be
  32.      translated and executed by the device.
  33.        Device: "CON:"
  34.  
  35.   3. Unbuffered and untranslated (raw) console handler (input/
  36.      output in a "Console window").
  37.        Device: "RAW:"
  38.  
  39.   4. Printer handler. With help of Preferences translated and
  40.      buffered printer output to either the parallel or serial
  41.      port depending on the preference settings.
  42.        Device: "PRT:"
  43.  
  44.   5. Parallel handler. Buffered parallel input/output.
  45.        Device: "PAR:"
  46.  
  47.   6. Serial handler. Buffered serial input/output.
  48.        Device: "SER:"
  49.  
  50.   7. Unbuffered and untranslated serial input/output.
  51.        Device: "AUX:"
  52.  
  53.   8. Translated output to the Amiga's speech synthesizer.
  54.        Device: "SPEAK:"
  55.  
  56.   9. Buffered data input/output transferring with other
  57.      programs.
  58.        Device: "PIPE:"
  59.     
  60.   10. Output to nothing.
  61.        Device: "NIL:"
  62.  
  63.  
  64.  
  65. 6.3  CONSOLE WINDOWS
  66.  
  67. One very useful thing is the Amiga's "Console windows". It is a
  68. window in which your program can communicate with the user. You
  69. can send text to the window and collect input from the user.
  70. The communication can be both buffered and unbuffered.
  71.  
  72. If the text in a console window does not fit it will be
  73. scrolled, and if the user then makes the window larger the
  74. previously hidden text parts will be displayed again. Console
  75. windows allows the user to edit the text line with help of the
  76. cursor keys, and the console window also stores the text lines
  77. the has typed so they can later be reused.
  78.  
  79. If the clipboard function is turned on (the "ConClip" program
  80. has been started, automatically done in the startup-sequence)
  81. the console windows even use the Clipboard to copy and paste
  82. data from and to other applications. (This clipboard support
  83. was introdused in Release 2).
  84.  
  85. There exist two types of console windows. First we have the
  86. normal "CON:" device which uses a buffer and translates some
  87. of the characters that are sent into special commands that
  88. will for example turn on bold, italic, change pen colour,
  89. flash the screen etc... The other type of console windows is
  90. the "RAW:" device which does not use any buffer nor will the
  91. characters be translated.
  92.  
  93.  
  94. 6.3.1  OPEN CONSOLE WINDOWS
  95.  
  96. To open a console window you simply use the Open() function
  97. as you do with files. But instead of giving the Open() function
  98. a file name you give it a "console description" which tells
  99. the AmigaDOS how you want the window to be opned, what size,
  100. position etc.. The syntax for the console window is:
  101.  
  102.   "device:x/y/width/height/title/option(s)"
  103.  
  104.   device:  Can either be "CON:" (buffered and translated) or
  105.            "RAW:" (unbuffered and untranslated).
  106.  
  107.   x:       X position of the window.
  108.  
  109.   y:       Y position of the window.
  110.  
  111.   width:   The width of the window.
  112.  
  113.   height:  The hight of the window.
  114.  
  115.   title:   A window title (may contain spaces).
  116.  
  117.   options: You can set zero or more of the below sepcified
  118.            flags. Note that you must put a slash (/=) betweem
  119.            each flag.
  120.  
  121.   Flag       Description
  122.   -------------------------------------------------------------
  123.   /AUTO:     Opens the window first when there is some IO
  124.   /BACKDROP: Should be a "backdrop" window (no other window can
  125.              be moved behind it)
  126.   /CLOSE:    Add a close window gadget
  127.   /NOBORDER: Draw no borders around the window
  128.   /NODRAG:   Remove the drag gadget
  129.   /NOSIZE:   Remove the size gadget
  130.   /SCREEN:   Open on a specified public screen "/SCREEN [name]"
  131.   /SIMPLE    The window should use "simple refresh" mode
  132.              (see Intuition manual for more information)
  133.   /SMART:    The window should use the "smart refresh" mode
  134.              (see Intuition manual for more information)
  135.   /WAIT:     Waits with closing the window until the user types
  136.              "Ctrl-\" or clicks on the close window gadget 
  137.   /WINDOW:   Use the specified window (address in hexadecimal)
  138.              "/WINDOW [pointer to window]"
  139.  
  140.  
  141. If you could successfully open the console window the Open()
  142. function will return a BCPL pointer to your console window.
  143. This pointer should be used as you normally do with simple file
  144. pointers. Actualy there is no difference between a file and a
  145. console window pointer. This is why you can use the normal file
  146. functions on console windows and any other type of handler as
  147. well.
  148.  
  149. Here is an exmple on how to open a console window:
  150.  
  151.   /* A "BCPL" pointer to our console window: */
  152.   BPTR my_console;
  153.  
  154.   - - -
  155.  
  156.   /* Open a console window: */
  157.   my_console = 
  158.    Open( "CON:10/50/320/100/My Console!/CLOSE/WAIT", MODE_NEWFILE );
  159.   
  160.   /* Could we open the console window? */
  161.   if( my_console == NULL )
  162.   {
  163.     /* Inform the user: */
  164.     printf( "Error! Could not open the console window!\n" );
  165.  
  166.     /* Exit with an error code: */
  167.     exit( 20 );
  168.   }
  169.  
  170.  
  171.  
  172. 6.3.2  OUTPUT TO CONSOLE WINDOWS
  173.  
  174. Once you have successfully opened a console window window you
  175. can start to write (send, output) and read (collect, input)
  176. data with help of the normal Read() and Write() functions.
  177.  
  178. If you have used the "CON:" device you can include "ANSI
  179. Console Control Sequences" which will be translated into
  180. different types of commands like "turn on bold", "set pen
  181. colour to 4", "flash the screen", etc.. See Appendix "ANSI
  182. Console Control Sequences" for a complete list of all available
  183. console commands.
  184.  
  185. Here is an example on how to send text to a console window:
  186. (Output)
  187.  
  188.   /* Store the number of characters (bytes) */
  189.   /* actualy written here:                  */
  190.   int characters_written;
  191.  
  192.   /* The text we want to print. Note the new line */
  193.   /* character "\n" and the tab character "\t".   */
  194.   /* The reult will be:                           */
  195.   /*                                              */
  196.   /* Dear User,                                   */
  197.   /*                                              */
  198.   /* Bla Bla...                                   */
  199.   /*                                              */
  200.   /*         Yours Sincerely,                     */
  201.   /*         -AB-                                 */
  202.  
  203.   UBYTE *my_text =
  204.     "Dear User,\n\nBla Bla...\n\n\tYous Sincerely,\n\t-AB-";
  205.  
  206.   - - -
  207.  
  208.   /* Write the text: */
  209.   characters_written =
  210.     Write( file, my_text, strlen( my_text ) );
  211.  
  212.   /* Could we write all the text? */
  213.   if( characters_written != strlen( text ) )
  214.     printf( "Error! Could not write all text!\n" );
  215.  
  216.  
  217.  
  218. 6.3.3  INPUT FROM CONSOLE WINDOWS
  219.  
  220. When you use the Read() function it will first return when
  221. the user hits the Return or Enter key. Note that the number of
  222. characters (bytes) collected depends on how many the user
  223. typed before he/she pressed the Enter or Return key.
  224.  
  225. Note that there will not be any NULL sign at the end of the
  226. collected string! There will however be an "Enter" sign (since
  227. the used has to hit Enter or Return to continue). If you want
  228. to use the collected data you must therefore add a NULL sign,
  229. and possible also remove the Enter sign (not necessary, but if
  230. you print the string the Enter sign will also be printed and
  231. consequently move down the cursor one line, and this is
  232. probably not wanted). 
  233.  
  234.   If the user entered four characters and then pressed Return
  235.   or Enter, 5 characters will be collected.
  236.  
  237.   If the user did not enter any characterrs at all and simply
  238.   pressed Return or Enter on an empty line, 1 character will be
  239.   collected.
  240.  
  241.   If the user did not enter anything but instead closed the
  242.   window, 0 characters will be collected. (If the user entered
  243.   some characters before he/she pressed enter those characters
  244.   will be collected, but then there will of course not be any
  245.   enter sign at the end of the string.)
  246.  
  247. Here is an example on how to collect text from a console
  248. window: (Input)
  249.  
  250.   /* Size of the buffer: */
  251.   #define MAX_LENGTH 256
  252.  
  253.   /* Store the number of characters (bytes) */
  254.   /* actualy read here:                     */
  255.   int characters_read;
  256.  
  257.   /* Declare a small buffer in which the collected */
  258.   /* data can be stored.                           */
  259.   UBYTE my_buffer[ MAX_LENGTH ];
  260.  
  261.   - - -
  262.  
  263.   /* Collect some text: */
  264.   characters_read = Read( file, text, MAX_LENGTH );
  265.  
  266.   /* In the buffer there will now probably be some text, and   */
  267.   /* at the end of the text there will be an "Enter" sign. The */
  268.   /* Read() function will first return when the user hits the  */
  269.   /* enter key (or closes the window). What comes after the    */
  270.   /* enter sign is rubbish and should not be used.             */
  271.   /*                                                           */
  272.   /* To be able to print the text we need to put a NULL sign   */
  273.   /* at the end of the string. (All strings must end with a    */
  274.   /* NULL sign, otherwise the functions would not know when    */
  275.   /* the string ends.) To also get rid of the Enter sign we    */
  276.   /* simply substitute it with a NULL sign:                    */
  277.   
  278.   /* Put the NULL ('\0') sign at the end of the string: */
  279.   if( characters_read > 0 )
  280.   {
  281.     /* Substitute the Enter sign with a NULL sign: */
  282.     text[ characters_read - 1 ] = NULL;
  283.   }
  284.   else
  285.   {
  286.     /* Nothing was entered, not even an Enter sign! */
  287.     /* The console window has been closed!          */
  288.     printf( "The console window was closed!\n" );
  289.  
  290.     /* Clear the string: (Set a NULL sign in the begining) */
  291.     text[ characters_read ] = NULL;
  292.   }
  293.  
  294.  
  295.  
  296. 6.3.4  CLOSE CONSOLE WINDOWS
  297.  
  298. To close the console window simply call the Close() function.
  299. The window will usually close immediately, but if you have set
  300. the flag "\WAIT" the window will first close when the user hits
  301. "Ctrl-\" (holds down the "Ctrl" key and the "\" key). If the
  302. window has a close gadget the user can also use that one.
  303.  
  304. The advantage with the "\WAIT" flag is that your program can
  305. print some information in a console window and then close it
  306. and terminate, but the window will still be left on the screen
  307. until the user has read your message and closes the window.
  308.  
  309. If the user tries to close the window before you have closed
  310. it all remaining Read() and Write() requests will immediately
  311. return, and no characters written or collected.
  312.  
  313. Here is an example on how to close a console window: (extremely
  314. tricky...)
  315.  
  316.   /* Close the console window: */
  317.   Close( my_console );
  318.  
  319.  
  320.  
  321. 6.4  PRINTER
  322.  
  323. You can even use AmigaDOS to print text with a printer. You
  324. simply open the "PRT:" handler as any other handler, and
  325. everything you then write will be printed. Since the "PRT:"
  326. handler uses the settings in Preferences the output will
  327. automatically directed to the right port which the printer
  328. is connected to (the parallel or serial port), and the
  329. characters and commands are translated to fit the in
  330. Preferences specified printer.
  331.  
  332. You can of course only write data to the printer (only
  333. output).
  334.  
  335. Since Preferences is used to translate all data which are going
  336. to be printed you can use the commands listed in appendix
  337. "Printer Commands" to turn on bold, italics, NLQ, etc...
  338.  
  339. Here is an example on how to use the "PRT:" handler:
  340.  
  341.   /* The text we want to print: */
  342.   UBYTE *my_text = "This will be printed!\f";
  343.  
  344.   /* A "BCPL" pointer to our Printer handler: */
  345.   BPTR my_printer;
  346.   
  347.   /* Store here the number of characters actually printed: */
  348.   long characters_printed;
  349.  
  350.   - - -
  351.  
  352.   /* Open the Printer handler ("PRT:"): */
  353.   my_printer = Open( "PRT:", MODE_NEWFILE );
  354.   
  355.   /* Have we opened the Printer handler successfully? */
  356.   if( !my_printer )
  357.   {
  358.     /* Inform the user: */
  359.     printf( "Error! Could not open the Printer handler!\n" );
  360.  
  361.     /* Exit with an error code: */
  362.     exit( 20 );
  363.   }
  364.  
  365.   - - -
  366.  
  367.   /* Print the text: */
  368.   characters_printed = 
  369.     Write( my_printer, my_text, strlen( my_text ) );
  370.  
  371.   /* Could we print all characters? */
  372.   if( characters_printed != strlen( my_text[ loop ] ) )
  373.     printf( "Error! Could not print all text!\n" );
  374.  
  375.   - - -
  376.  
  377.   /* Close the Printer handler: */
  378.   Close( my_printer );
  379.  
  380.  
  381.  
  382. 6.5  USE THE PARALLEL PORT  
  383.  
  384. To use the parallel port is also very simple. You open it as
  385. normal, with the name "PAR:", and everything you read or write
  386. will be done on the parallel port. Note that no translation is
  387. done (only raw unmodified values are sent/received). The
  388. parallel port can be used for both input, Read(), and output,
  389. Write().
  390.  
  391. Note! The PAR: handler should NOT be used to print things! Use
  392. the PRT: handler instead!
  393.  
  394.  
  395.  
  396. 6.6  USE THE SERIAL PORT
  397.  
  398. The serail port is as equal simple as the parallel port. You
  399. open it as normal, with the name "SER:", and everything you
  400. read or write will be done on the serial port. Note that no
  401. translation is done (only raw unmodified values are sent/
  402. received). The serial port can be used for both input, Read(),
  403. and output, Write().
  404.  
  405. Note! The SER: handler should NOT be used to print things! Use
  406. the PRT: handler instead!
  407.  
  408.  
  409.  
  410. 6.7  THE AUX: HANDLER
  411.  
  412. The AUX: handler is an unbuffered serial input/output handler
  413. which will not be described here since it is never used by most
  414. of us. (I have never used it myself so I prefer not to explain
  415. it.)
  416.  
  417.  
  418.  
  419. 6.9  USE THE SPEECH SYNTHESIZER
  420.  
  421. The Amiga's speech synthesizer is a device which is sadly
  422. rarely used, but can really be useful. With Release 2 it will
  423. now even sound much better, so use it if you can. In fact, I
  424. think most programs should have an option to turn on the
  425. speech synthesizer so it will be used to read out loud
  426. every single message that is printed. You should of course
  427. never use the speech synthesizer only since many users can not
  428. hear very good, but as an extra medium of communication it is
  429. excellent!
  430.  
  431. To use the speech synthesizer handler is equally simple as all
  432. other handlers. You only have to open the "SPEAK:" device, and
  433. everything you sent do it with help of Write() will
  434. automatically be translated and read out loud. You can of course
  435. only send text to the device and not read (output only).
  436.  
  437. When you open the speaker handler you can change some of the
  438. default values in order to alter the sound: (The slash "/"
  439. must be included before every option.)
  440.  
  441.   Syntax: SPEAK:OPT opt1/opt2/opt3...
  442.  
  443.   Option  Description
  444.   ----------------------------------------------------
  445.   /n      Speak with a natural voice
  446.   /m      Speak with a man voice
  447.   /f      Speak with a "female" voice
  448.   /r      Speak like a robot with a monototonous voice
  449.   /sXXX   Speed, 40 - 400
  450.   /pXXX   Pitch, 65 - 320
  451.  
  452. Here is an example on how to let the Amiga read some text:
  453.  
  454.   /* Here is the text we want the Amiga to read: */
  455.   UBYTE *my_text = "Only the Amiga makes it possible!";
  456.  
  457.   /* A "BCPL" pointer to our Speaker handler: */
  458.   BPTR my_translator;
  459.   
  460.   /* Store here the number of characters actually spoken: */
  461.   long characters_spoken;
  462.  
  463.   - - -
  464.  
  465.   /* Open the Speaker handler, use "female" voice and fast: */
  466.   my_translator = 
  467.    Open( "SPEAK:OPT/f/s250", MODE_NEWFILE );
  468.   
  469.   /* Have we opened the Speaker handler successfully? */
  470.   if( my_translator == NULL )
  471.   {
  472.     /* Problems, inform the user: */
  473.     printf( "Error! Could not open the Speaker handler!\n" );
  474.  
  475.     /* Exit with an error code: */
  476.     exit( 20 );
  477.   }
  478.  
  479.   - - - 
  480.  
  481.   /* "And I could hear her say..." */
  482.   characters_spoken =
  483.     Write( my_translator, my_text, strlen( my_text ) );
  484.  
  485.   /* Was the whole line "read": */
  486.   if( characters_spoken != strlen( my_text ) )
  487.     printf( "Error! Could not \"read\" all text!\n" );
  488.  
  489.   - - -
  490.  
  491.   /* Close the Speaker handler: */
  492.   Close( my_translator );
  493.  
  494.  
  495.  
  496. 6.11  TRANSFER DATA BETWEEN PROGRAMS
  497.  
  498. Since there may be several progreams running at the same time
  499. you sometimes may want to transfer a lot of data between to
  500. programs. You could of course use a temporary file in which
  501. the "sender" saves all data so the "receiver" later can read
  502. it.
  503.  
  504. This is, however, not a very good solution since an unnecessary
  505. file must be created, and if you want to transfer a lot of data
  506. it would have to be very big. Secondly it is rather unefficient
  507. since it takes some time to pen a file, save all data, close it
  508. again so the other program can open it, read the data and then
  509. finally close it again.
  510.  
  511. The programs should insted use is the special "PIPE:" handler
  512. which allows programs to send data to each other at very high
  513. speed. (See picture "PipeHandler.pic")
  514.  
  515. When you open the "PIPE:" handler you can give it a "piper
  516. name" (the name of the temporary buffer where all data will be
  517. temporarily stored) although it is not necessary. Since there
  518. may be several programs using the piper handler I recommend
  519. you to use some sort of piper name.
  520.  
  521.   Syntax: PIPE:[piper name]
  522.  
  523. The first program that opens the piper handler should open it
  524. as "MODE_NEWFILE" and the other as "MODE_OLDFILE". However, you
  525. can equaly well first open it as an old file and then as a new
  526. file, but that might look a bit strange. The only really
  527. important thing is that one program opens it as a new file and
  528. the other as an old (both programs may not open it as new, or
  529. both as old).
  530.  
  531. Once a program has opened a piper handler it can start to send
  532. or collect data. (The other program does not have to open the
  533. piper handler before the first program can use it.)
  534.  
  535. You send data with help of the Write() function as normal. You
  536. should note that the piper handler is using a small buffer of
  537. around 4 kB, and once the buffer has been filled any further
  538. write requests will be halted until someone empties the buffer.
  539. (Your program will simply be put to sleep until someone
  540. collects the data in the buffer and your read request can be
  541. satisfied.)
  542.  
  543. You collect data with help of the Read() function as normal.
  544. However, if there is no data in the temporary buffer the read
  545. request will be halted until all characters as requested has
  546. been collected or the other program closes the handler:
  547.  
  548.   If program A sends 10 characters but you tried to read 15
  549.   characters your program will be put to sleep until 5 more
  550.   characters have been sent by A, or the piper handler was
  551.   closed by A.
  552.  
  553. See programs "Example5A.c" and "Example5B.c" more information.
  554.  
  555.  
  556.  
  557. 6.10  OUTPUT TO NIL:
  558.  
  559. The "NIL:" handler is often used when you write scripts for the
  560. Shell or CLI and want all output to vanish. However, in a
  561. program you hardly use it at all.
  562.  
  563. Everything you send to to NIL: will simply disappear. It is
  564. used like all other handlers, but can of course only be used
  565. for output.
  566.